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ABSTRACT 

This  thesis  describes  the  concept  of  an  input  and  output 
filter  for  the  Warfare  Environment  Simulator  (WES).  The 
filter  is  comprised  of  two  computer  programs  which  were 
written  in  the  "c"  programming  language.  The  main  program 
examines  the  input  to  the  filter  on  a  character  by  character 
basis,  and  provides  two  basic  capabilities  which  are  not 
currently  available  in  WES.  The  first  is  the  ability  to 
edit  or  create  files,  and  the  second  is  a  facility  for 
translating  abbreviations  (macros)  into  WES  commands.  The 
macros  may  include  values  which  are  substituted  into 
variables  in  the  commands  as  they  are  sent  to  WES.  The 
second  program  buffers  the  output  from  WES  as  directed  by 
the  main  program  to  avoid  an  interleaving  of  output  when  a 
process  other  than  WES  is  in  use. 
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I .   BACKGROUND 

A.   OBJECTIVE 

The  objective  of  this  thesis  was  to  develop  a  "filter" 
program  for  the  Warfare  Environment  Simulator  (WES).   It  was 
envisioned  that  the  program  would  continuously  examine  the 
characters  which  were  being  typed  in  to  determine  if  a 
predetermined  set  of  characters  (a  "string")  was  present, 
and  if  so,  to  perform  some  corresponding,  and  also 
predetermined  function.   Additionally,  the  program  would  he 
capable  of  buffering  output  from  WES  in  the  event  that 
output  from  some  other  process  is  being  displayed  on  the 
terminal.   Eor  example,  tbis  would  allow  for  the  use  of  an 
editor,  since  the  output  from  WES  could  be  saved,  and  later 
displayed  on  the  terminal  when  the  editing  session  was 
completed.   This  objective  was  met  in  the  manner  described 
in  the  following  section. 


B.   INTRODUCTION 

In  achieving  the  stated  objective,  two  major  questions 
had  to  be  answered.   The  first  question  was  "What  functions 
would  be  most  useful  in  the  implementat i en  of  the  filter 
concept  ?"   Those  who  were  most  familiar  with  the  operation 
of  WES  were  the  least  concerned  about  functions  which  would 
make  it  easier  to  use:  as  usual,  once  a  system  has  already 


been  learned,  almost  by  definition  its  use  becomes  easy.   On 
the  other  hand,  since  the  majority  cf- those  who  have  tried 
to  use  WES  have  been  initially  overwhelmed  Dy  its 
complexity,  they  provided  many  suggestions  as  to  what 
capabilities  the  filter  program  should  proviie.   The  second 
question  was  'How  will  the  program  determine  when  a 
particular  function  is  to  be  performed  ?,"  or  similarly, 
"How  will  the  user  indicate  that  a  function  is  to  be 
performed  ?"   The  answer  to  this  question  will  be  addressed 
first. 

To  enable  a  user  cf  the  program  tc  distinguish  between 
input  to  WES  and  a  "command"  to  the  filter  program,  a 
special  character  (the  "?")  was  chosen.   It  must  precede  any 
input  which  is  to  be  interpreted  bj   the  program.   For 
example,  if  "help"  was  typed  in,  it  would  be  passed  through 
the  filter  to  WES  without  any  action  being  taken  by  the 
program,  while  "Shelp"  would  cause  the  program  to  display 
the  help  file  without  sending  any  characters  to  WES. 

Answering  the  first  question  was  a  much  more  difficult 
task.   The  answer  lies  in  the  intersection  of  two  lists  of 
capabilities  -  a  list  of  what  would  te  rrost  useful  to 
implement,  and  a  list  cf  what  is  reasonable  to  implement. 
The  adjective  reasonable  in  this  context  means  feasible  in 
terms  of  the  limitations  imposed  by:  (i)  the  programming 
language  being  used  ("c"),  (2)  the  operating  system  (UNIX) 
and  the  standard  routines  it  has  access  to,  and  (3)  the  time 


available  to  write  the  program  or  subroutine.  All  of  these 
factors  were  taken  into  account  when  the  filter  concept  was 
developed  and  implemented. 

A  review  of  the  capabilities  which  were  common  to  the 
two  lists  resulted  in  a  decision  to  include  the  following 
functions  in  the  filter  program: 

1.  An  editing  capability  for  reviewing  old  files,  or 
creating  new  ones . 

2.  A  means  of  identifying  certain  brief  strings  of  input, 
and  sending  a  much  more  complex  series  of  characters  to 
WES. 

3.  A  mechanism  for  substituting  arguments  provided  as  input 
for  variables  in  predefined  WIS  commands. 

4.  A  "default"  mcae  of  operation  in  which  input  provided  tc, 
as  well  as  output  from,  WIS  occurs  as  it  would  if  the 
filter  program  were  not  being  used. 

A  detailed  description  of  how  tnese  functions  are  performed 

is  the  topic  of  the  next  section. 
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II .   PROGRAM  STRUCTURE  AND  DESCRIPTION 

A.   THI  MAIN  PROGRAM 
1 .   General 

The  main  program  receives  input  from  the  Keyboard, 
checks  for  the  special  character,  and  either  passes  the 
other  characters  to  telnet  or  responds  to  the  "special" 
character  strings  as  if  the/  were  commands.   The  special 
character  for  this  program  is  the  dollar  sign  ("s").   A  "$" 
causes  the  program  to  compare  the  characters  immediately 
following  it  to  a  list  of  strings  of  characters  which 
correspond  to  subroutines  v»hich  are  to  he  performed.   If  the 
input  string  does  not  match  a  string  in  the  list,  an  error 
message  is  generated  and  nc  action  is  taken. 

These  twc  modes  of  operation,  as  indicated  in  the 
source  code,  are  (1)  the  "default"  mode,  and  (2)  the  "call 
subroutine"  mcde.   In  the  former,  all  input  characters  are 
sent  to  telnet,  with  the  echo  (a  copy  of  the  character  on 
the  terminal  screen)  being  provided  by  the  remote  host.   In 
the  latter,  the  input  characters  are  used  to  control  the 
program,  which  performs  various  functions  which  are  not 
otherwise  available  while  running  the  WES  program.   These 
functions  include  listing  the  available  files,  invoicing  the 
editor,  and  expanding  abbreviations  (later  referred  to  as 
macros)  into  standard  WES  commands. 

11 


The  filter  process  was  designed  to  be   file  driven  . 
For  the  most  part,  the  text  fcbicb  is  required  for  display  in 
the  rrain  program  is  contained  in  separate  files  which  are 
opened,  read,  and  copied  to  tbe  terminal.   This  allows  for 
the  text  to  be  easily  changed  as  necessary,  and  results  in  a 
shorter  prograrr.   This  tradeoff  is  in  favor  of  both 
simplicity,  and  flexibility  for  future  expansion  or 
modification.   It  should  be  noted  that  this  flexibility  does 
not  extend  to  changing  the  menu  text  without  changing  the 
switches  in  the  main  program  which  control  the  response  of 
the  program  to  the  selection  of  an  option. 

Aside  from  the  subroutines,  the  overall  program  is 
divided  into  three  distinct  parts  (Figure  1).   The  main 
program  controls  the  overall  filter  process.   It  also  causes 
an  asynchronous  program  to  be  executed  which  receives  the 
output  from  telnet  (which  is  the  output  from  WES  in  this 
case),  and  either  sends  it  directly  to  the  terminal  or 
stores  it  while  ether  information  is  being  displayed.   This 
buffer  program  is  discussed  in  more  detail  in  section  II  C. 
The  third  part  of  the  program  is  the  telnet  process,  which 
will  be  discussed  in  section  II  E . 
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[" filter. c"  ] 


+• 


i  THE   MAIN  ! 
!   PROGRAM   |\ 


+  \ 

\ 
\ 
init( )         \ 
menu( }  \ 

macro ( )  \ 

nextO  \ 

xlate()  \ 

sub()  \ 

edit()  \ 

display!  )  \       I   "telnet'"   ] 

rvvMacrc ( )  \ 

orderPrepO  \     + + 

rvvOraersO  \     !  THE  TELNET  | 

tnTcps20()  !    PROCESS    ! 

c3LabLinU:()  /    + + 

helpO  / 

err()  /   [  CONNECTS  THE  FILTER  ] 

quit(  )  /    [      TO  TCPS20       ] 

popen( )  / 

pclose( )  / 


/ 


[  "readTN.c"  ]   / 

/ 


/ 


+  / 

THE   BUEEER  !/  [  RECEIVES  THE  OUTPUT  EROM  ] 

PROGRAM    j  [  TELNET  AND  BUEFERS  IT  AS  ] 

+  [  REQUIRED          ] 


'igure  1.   PROGRAM  STRUCTUR 
13 


2.   The  Subroutines 

The  subroutine  "init()"  executes  the  actions  which 
are  required  to  begin  using  the  program  (Figure  2).   The 
most  significant  of  these  actions  are  as  follows: 

1.  Reading  the  macros  and  their  WES  equivalents  into  an 
array  so  that  the  program  can  rapidly  determine  if  an 
input  string  is  a  valid  macro,  and  if  it  is,  output  the 
WES  command. 

2.  Determining  the  type  of  terminal  that  is  being  used,  so 
that  the  proper  (either  line  or  full  screen)  editor  can 
be  called,  if  required. 

3.  Determining  whether  the  program  will  be  used  with  telnet, 
or  for  training  on  the  capabilities  and  operation  of  the 
program. 

The  subroutine  which  controls  the  display  and 
selection  of  options  is  "menuO".   A  text  file  containing 
the  menu  of  options  is  displayed,  and  a  number  corresponding 
to  the  option  selected  is  entered  (Figure  3).   The 
appropriate  subroutine  is  then  called.   After  an  option  has 
been  completed,  the  menu  is  displayed  again,  and  another 
choice  may  be  made.   Returning  to  the  standard  WES  input 
mode  is  the  last  option  on  the  menu. 

The  following  options  are  available  in  the  menu 
(with  the  exception  of  "4"  which  has  not  been  implemented/: 

1.  Editing  an  existing  file,  cr  creating  a  new  file. 

2.  Displaying  the  current  list  of  filenames. 

3.  Editing  the  list  of  macros  and  their  WES  equivalents. 

4.  Preparing  an  order  for  input  to  WES. 

5.  Displaying  the  current  list  of  orders. 

6.  Returning  to  the  standard  WES  input  mode. 
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[  THE  FILE  "mac. text"  IS  OPENED  AND  READ  INTO  ] 
[     THE  ARRAY  "mac  [] "  IN  THE  MAIN  PROGRAM    ] 


***  TYPE  IN  1  OR  2.*** 


Fri  Mar  5  21:06:10  PST  Iy82  | 


WHAT  TYPE  OF  TERMINAL  ARE  YOU  WOREING  ON  ? 


1.  Ann  Arbor. 

2.  Digital  VT  100. 

3.  A.D.M.3  or  Tektronix. 


***  TYPE  IN  1,  2  OR  3.***  ! 

i 
i 

1  < 1  A  "l"  WAS  TYPED  IN  HERE  TO  INDICATE  THAT 

[  THE  TERMINAL  BEING  USED  WAS  AN  ANN  ARBOR  ] 

i 

! 

WELCOME  -  You  have  the  following  options:  ! 

i 

1.  Telnet  to  Toos20  and  log  in  automatically. 

i 
i 

2.  Link:  to  another  terminal  in  the  C-3  Lab 

(primarily  for  training  on  this  program). 

i 
i 
i 

i 
i 
i 
i 
i 

! 
I 


2  < L  A  "2"  WAS  TYPED  IN  HERE  TO  INDICATE  THAT  ] 

[    PROGRAM  WAS  TO  BE  USED  FOR  TRAINING     ] 


[  THIS  RESULTS  IN  A  CALL  TC  " c3LabLi nk( ) "  ]         ! 


Figure  2.   SUBROUTINE  "init() 
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I  TYPING  "$"  AND  A  CARRIAGE  RETURN  CAUSES  ] 
[    TEE  FOLLOWING  MENU  TO  BE  DISPLAYED 


MENU  #1  -  You  have  the  following  options: 

1.  Review/Edit  an  existing  file. 

2.  See  the  current  list  of  filenames. 

3.  Review/Edit  the  current  macro  list. 

4.  Prepare  an  order. 

5.  See  the  current  list  of  orders. 

6.  Cuit  (return  to  standard  WES  input  mode). 

***  Type  in  1,  2,  3,  4,  5,  or  6.  *** 

6  < 1  A  "6"  TYPED  HERE  CAUSES  THE  PROGRAM  TO   ] 

[   RETURN  TO  THE  STANDARD  WES  INPUT  MODE   ] 


[  OPTION  4  HAS  BEEN  INCLUDED  BOTH  HERE  AND  1 

IN  THE  SOURCE  CODE  TO  DEMONSTRATE  AN 
[  OPTION  WHICH  MAY  BE  ADDED  TO  THE  PROGRAM  ] 
IN  TEE  FUTURE,  AND  AS  AN  EXAMPLE  OE  HOW  ] 
[     EASILY  A  MODULE  MAY  BE  ADDED  TO  THE 
[  PROGRAM  ] 


0  < [  THIS  IS  THE  OPERATING  SYSTEM  PROMPT  FROM  ] 

[   TOPS20,  WHICH  IS  DISPLAYED  AFTER  OPTION  ] 
[  "6"  HAS  BEEN  SELECTED  ] 


Figure  3.   SUBROUTINE  "menu( 


Items  4  and  5  have  been  included  in  the  menu  as  an  example 
of  a  potential  area  for  expanding  the  program  oeyond  its 
capabilities  as  it  is  currently  written.   If  option  4  (order 
preparation;  is  selected,  a  message  is  returned  stating  that 
the  option  is  not  implemented  yet.   Option  5,  however,  does 
list  the  files  in  the  directory  which  end  in  ".ord"  ;  this 
can  easily  be  changed  to  any  ending  which  would  readily 
identify  the  files  containing  standard  groups  of  orders  for 
input  to  WES.   This  will  be  discussed  in  more  detail  in 
Chapter  IV. 

The  most  complex  series  of  subroutines  begins  with 
"macroO"  (Figure  4).   This  family  of  routines  includes 
"macro!)",  "nextO",  "xlateO",  and  "sub()".   They  are  used 
to  accomplish  two  closely  related  tasks,  both  of  wbich  are 
controlled  by  "macro!)". 

The  first  task  is  the  substitution  of  a  WIS  command, 
or  a  series  of  WES  commands  for  an  abbreviation  (macro) 
which  is  defined  ana  entered  into  the  file  "mac. text".   This 
file  may  be  changed  at  any  time  by  choosing  menu  option  3. 
The  file  is  stored  in  an  array  in  the  program  to  facilitate 
a  rapid  search  and  translate  process.   To  expand  a  simple 
macro,  a  "s"  is  entered,  followed  by  the  macro  and  a 
carriage  return.   If  the  macro  is  to  be  used  at  the 
beginning  (or  in  the  middle)  of  a  sentence,  the  macro  is 
ended  with  the  character  "escaoe". 
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[  "macro!  )'"  EXAMINES  THE  INPUT  FOLLOWING  A  ] 

[  "$"  IF  THE  INPUT  DOES  NOT  CORRESPOND  TO 

r  A  PREDETERMINED  FUNCTION  WITHIN  TEE 

L  PROGRAM  SUCH  AS  "belpO"  OR  "quitO" 


SUCCESSIVE  CALLS  TO  NEXT  ARE  REQUIRED  TO 
DETERMINE  IF  A  MACRO  EXISTS  WHICH 
MATCHES  THE  CHARACTERS  WHICH  ARE  BEING 
TYPED  IN. 

IF  A  CHARACTER  IS  TYPED  IN  WHICH  DOES 
NOT  MATCH  A  MACRO  IN  THE  CURRENT  LIST, 
AN  ERROR  MESSAGE  IS  DISPLAYED 


[   THE  ERROR  MESSAGE  -  "NOT  A  VALID  MACRO"  ] 


Figure  4.   SUBROUTINES  "macroO"  AND  "nextO 


This  causes  the  expansion  of  the  macro  to  "be  sent  to  WES, 
but  it  is  net  folicwed  by  a  carriage  return.   This  type  of 
expansion  is  useful  for  sending  commands  which  are 
frequently  used  during  the  conduct  of  a  game,  especially 
since  a  new  macro  can  he  added  to  the  file  while  the  game  is 
in  progress. 

The  second  task  is  an  extension  of  the  first  in 
which  a  macro  with  arguments  is  expanded  into  one  or  more 
'*ES  commands.   After  the  macro  and  its  expansion  are  found 
in  the  array,  the  arguments  are  substituted  into  their 
appropriate  places  in  the  commands  as  they  are  sent  to  WIS. 
For  example,  if  "Satk.a?( nimi tz ,4 , fl tl) "  is  entered,  the 
following  actions  are  taken.   "Macro!)"  is  called  as  soon  as 
enough  characters  are  entered  to  determine  that  the  input  is 
not  a  request  for  one  of  the  programs  standard  routines, 
e.g.  "helpO".   In  this  case,  the  letter  "a"  is  sufficient 
to  make  this  decision.   Successive  calls  to  "nextO"  are 
made  as  required  to  match  the  string  of  characters  as  it  is 
being  typed  in.   This  serves  two  functions.   First,  no  delay 
is  required  to  locate  the  macro  and  send  the  WES  equivalent. 
Second,  as  soon  as  a  character  is  typed  in  which  causes  the 
string  of  characters  to  be  different  from  the  list  of  macros 
in  "mac. text",  an  error  message  ("NOT  A  VALID  fACSC" )  is 
displayed  and  the  program  returns  to  the  standard  WES  input 
mode . 
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After  "$atk.a7(nimi  tz  ,4,fi  tl)  "  is  entered,  it  must 
be  followed  by  a  carriage  return  cr  an  escape  character.   In 
either  case,  the  arguments  (nimitz,  4,  and  fitl)  are 
substituted  intc  the  appropriate  places  in  the  command  which 
is  sent  to  WES.   In  this  case,  the  output  to  WES  would  be 
"i'OR  NIMITZ  LAUNCH  4  A7E  iTLTl  120  240  1000".   Since  this  is 
a  macro  with  arguments,  the  substitution  and  output  to  WES 
is  accomplished  by  "sub()".   If  the  macro  did  not  have  any 
arguments,  the  translation  and  output  would  have  been 
accomplished  by  "ilate(}"  (Figure  5).   As  mentioned  earlier, 
following  a  macro  with  a  carriage  return  causes  a  carriage 
return  to  be  sent  to  WES,  while  an  escape  character  allows 
the  macro  expansion  to  be  used  ia  the  context  of  a  WES 
command  . 

"iditO"  is  the  routine  which  provides  the 
capability  to  review  an  existing  file  or  to  create  a  new 
file.   Since  the  type  of  terminal  being  used  is  determined 
in  "initO",  the  corresponding  type  of  editor  can  be  called. 
The  distinction  between  the  different  types  of  terminals 
must  be  made  by  the  program,  since  the  UNIX  operating  system 
is  not  capable  of  mating  the  distinction  on  its  own.   After 
entering  "editO",  the  name  of  the  file  which  is  to  be 
edited  must  be  entered.   Since  the  program  examines  every 
character  which  is  typed  in,  if  a  mistake  is  made  in  typing 
in  the  file  name,  no  provisions  exist  for  deleting 
characters  which  have  been  typed  incorrectly.   To  insure 
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that  this  is  not  a  problem,  the  program  asks  for  a 
verification  ^a  "y"  cr  "n")  of  the  name  which  has  been 
entered.   Once  in  the  editor,  the  program  is  no  longer 
examining  the  input,  and  the  editor  is  used  as  it  normally 
would  be.   As  a  minimum,  this  requires  the  user  to  fcnow  whet 
command  must  he  entered  in  order  to  exit  from  the  editor, 
since  the  program  cannot  oe  of  any  assistance.   Once  the 
editing  session  is  complete,  tne  menu  is  displayed  and 
another  selection  must  be  made.   Although  the  file 
containing  the  macros  may  be  edited  in  this  fashion,  a  menu 
option  has  been  provided  to  accomplish  this  directly  (Figure 
6). 

The  second  option  on  the  menu  is  to  display  the  list 
of  filenames  which  are  available  in  the  directory  which  was 
used  to  run  the  filter  program.   "DisplayO"  is  intended  to 
provide  a  list  of  files  if  a  particular  file  is  to  be  edited 
or  reviewed,  but  the  exact  name  cannot  be  remembered.   It 
presents  the  file  names  in  a  column  format,  so  that  all  the 
files  in  most  directories  will  be  available  on  the  screen  at 
one  time  (Figure  6).   To  return  to  the  menu,  any  character 
may  be  typed  in. 

As  previously  mentioned  in  the  discussion  on 
"edit()",  the  subroutine  "rvwMacroO"  automatically  calls 
the  macro  expansion  file  ("mar. text")  into  the  appropriate 
editor  (figure  6).   "Rvvl^acro  ( ) "  is  called  by  selecting  item 
3  on  the  menu.   This  routine  was  included  as  an  explicit 
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option  since  the  macro  expansion  capability  is  the  most 
powerful  option  available  in  the  program.   In  this  light, 
this  ability  to  rapidly  add  to  or  change  the  list  of  macros 
while  the  WES  program  is  running  should  prove  to  be  a 
desira  ble  f ea  ture  . 

As  mentioned  earlier,  the  subroutine  "orderPrep( ) " 
is  not  yet  implemented,  but  has  been  included  for  the 
following  reasons.   The  preparation  of  a  series  of  WES 
commands,  referred  to  here  as  an  order,  was  suggested  as  a 
useful  feature  to  be  added  to  the  program.   In  the  context 
of  WES  such  a  series  of  commands  would  be  called  a  "plan". 
This  routine  is  envisioned  to  use  a  menu,  from  which  small 
plans  would  be  selected  and  comcined  to  form  a  complete 
plan.   The  overall  plan  would  contain  stacdardized  control 
characters,  which  would  be  replaced  by  arguments  in  a 
routine  similar  to  "subO".   The  plan  could  then  be  typed 
out  or  edited  prior  to  being  sent  to  WES.   Although  this 
description  is  somewhat  limited,  it  should  provide  both  an 
explanation  of  the  concept  and  a  framework  on  which  to  build 
if  it  is  to  be  implemented. 

The  selection  of  the  next  item  on  the  menu  causes 
"rvwOrders( ) "  tc  be  executed.   This  routine  is  siTiiar  to 
"display!)",  in  that  it  lists  the  available  files  of  a 
certain  type,  in  this  case  files  which  contain  orders. 
These  files  are  currently  assumed  to  have  a  file  type,  or 
suffix,  of  ".crd".   This  suffix  can  he  easily  changed  within 
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the  program  to  one  which  is  more  easily  remembered  by  the 
user.   A  series  of  suffixes  can  also  be  entered  in  the 
program  if  a  more  general  listing  of  order  files  is  desired. 

The  next  subroutine  is  "tnTops2£ ( ) " ,  which  performs 
a  number  of  functions  if  the  option  to  use  telnet  is  chosen 
(Figure  ?).   first,  it  requests  that  two  processes  be 
initiated  -  telnet  and  "readTN".   The  output  from  telnet 
(WES)  is  sent  to  the  background  program,  "readTN".   This 
connection  is  established  using  the  UNIX  pipe  function  (!). 
However,  the  connection  between  the  filter  program  and 
telnet  is  created  in  the  program  using  "ropen()".   The  pipe 
facility  can  not  be  used  by   the  filter  since  a  pipe  sends 
all  of  the  output  of  the  first  process  to  the  second.   For 
example,  the  pipe  function  would  cause  the  menu  to  be  sent 
to  telnet,  which  obviously  would  not  be  desirable. 
"PopenO"  creates  a  file  descriptor,  which  is  essentially  a 
name  for  the  input  side  of  telnet.   Using  the  file 
descriptor,  selected  output  can  be  sent  to  telnet,  while 
ether  information  is  displayed  en  the  terminal  screen. 

As  will  be  aiscussed  more  thoroughly  in  Section  D  of 
this  chapter,  "tnTops20()"  also  selectively  adjusts  the 
terminal  moo.es,  which  would  otherwise  cause  the  keyboard  to 
become  inactive.   It  then  sends  the  file  "tr.Tcps20 .  text"  tc 
telnet.  The  file  contains  the  commands  tc  log  in  and  to 
begin  running  a  certain  program  if  desired.   This  is  an 
example  of  why  the  program  was  designed  to  be  file  driven, 
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for  changing  the  program  to  be  run  after  logging  in  is 
easily  accomplished  by  editing  the  "tnTops20 .text"  file. 

The  "helpO"  routine  is  the  first  of  the  standard 
routines  which  are  available  in  the  program  (Figure  3).   It 
consists  of  a  file  which  is  displayed  on  the  terminal  anl 
contains  the  basic  formats  for  input  to  the  filter  program. 
The  file  is  displayed  "by  typing  in  "$  help"  or  "$  ?".   The 
number  of  spaces  occuring  in  the  input  string  between  words 
in  this  case  is  net  significant,  e.g.,  "$   help"  and 
"shelp"  achieve  the  same  result.   However,  this  is  not  true 
for  all  input.   For  the  most  part,  the  input  tc  the  program 
is  in  the  form  of  WIS  commands,  which  are  handled  by  the 
"default  mode"  of  the  program,  and  as  such  are  sent  directly 
to  telnet  (toFb)  . 

The  second  standard  routine  is  "quit{)"  (Figure  8). 
It  is  requested  in  the  same  manner  as  the  help  function,  by 
typing  in  a  dollar  sign  followed  by  the  word  quit  ("$ 
quit").   Again,  the  number  of  spaces  between  the  two  words 
is  not  significant.   This  routine  is  used  to  exit  from  the 
program,  after  logging  off  of  the  system  at  NOSC.   Logging 
off  also  causes  the  telnet  process  to  be  terminated,  as 
indicated  by  a  message  on  the  terminal  when  this  occurs. 
The  filter  program  could  simply  be  aborted  at  this  point, 
however,  the  output  buffer  program  would  still  be  active, 
the  terminal  nodes  would  not  be  set  normally,  and  certain 
file  descriptors  would  still  be  open.   All  *he  tasxs 
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required  to  correct  these  deficiencies  are  accomplished  by 
"quitO".   A  message  indicating  that  the  filter  program  is 
being  exited  properly  is  displayed  as  these  tasks  are 
accomplished.   failure  to  use  the  quit  routine  will,  at 
best,  result  in  the  display  of  an  operating  system  prompt 
{"%")    with  input  from  the  Keyboard  being  accepted,  but  not 
echoed  (displayed)  on  the  terminal  as  it  is  typed  in. 

As  previously  mentioned  in  the  description  of 
"tnTops20  ( ) " ,  a  useful  connection  between  the  filter  pros-ram 
and  telnet  cannot  be  created  using  the  UNIX  pipe  facility. 
Rather,  the  subroutine  "popenO"  must  be  used  (?igure  9). 
The  creation  of  a  pipe  in  this  manner  allows  the  program  to 
send  only  selected  output  to  telnet.   "PopenO"  returns  a 
file  descriptor  which,  in  this  case,  is  essentially  the  name 
of  the  input  side  of  telnet.   The  output  which  is  intended 
for  telnet  is  then  directed  using  this  file  descriptor.   The 
procedure  for  properly  "closing"  this  file  descriptor  at  the 
end  of  the  program  is  discussed  in  the  following  paragraphs. 
Sufficient  comments  have  been  included  in  the  source  cede  to 
provide  more  details  as  to  exactly  how  "pcpen()"  functions. 
No  further  description  of  this  routine  will  be  included 
here. 

A  graceful  (i.e.,  correct  in  a  programming  sense) 
termination  of  the  filter  program  must  include  a  function 
which  closes  the  file  descriptor  ("fd")  which  is  created  in 
"popenO"  (Figure  9).   This  action  is  accomplished  in  the 
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subroutine  "pcloseO".   The  call  to  "pclcse()"  is  a  part  of 
the  "quitO"  routine  which  has  already  been  discussed. 

The  final  subroutine  in  the  program  is  "errO" 
(figure  3).   It  has  been  included  to  simplify  and 
standardize  the  inclusion  oi  error  checking  mechanisms  which 
are  found  throughout  the  program.   The  only  function  it 
performs  when  it  is  called  is  the  output  of  an  error  message 
en  the  terminal  screen. 

Due  to  the  fact  that  the  subroutines  are  file 
driven,  all  of  the  files  which  are  required  for  their 
operation  must  be  available  in  the  directory  from  which  the 
program  is  executed.   If  a  file  is  not  available,  and  an 
attempt  is  made  to  open  it,  an  error  will  result  which  will 
stop  the  program.   This  type  of  catastrophic  error  could  be 
avoided,  however,  the  program  would  be  at  test  handicapped 
by  the  absence  of  a  particular  file.   7or  this  reason,  it  is 
assumed  that  both  the  program  and  the  files  which  are 
required  to  run  it  in  its  entirety  will  be  available. 
Similarly,  the  "readTN"  program  must  remain  separate  from 
the  main  program,  and  it  too  must  be  in  the  directory  which 
is  being  used.   A  straightforward  means  of  insuring  that  all 
the  programs  and  files  are  accounted  for  is  tc  store  them 
all  on  a  tape,  and  to  read  the  tape  when  first  using  the 
filter,  or  when  an  error  occurs  because  a  required  file  has 
been  changed  or  deleted. 
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B.   THE  UNIX  INTERFACE 

In  general,  the  UNIX  interface  was  the  most 
straightf orward  concept  to  address  in  designing  and 
implementing  the  filter  program.   In  UNIX,  essentially  all 
areas  where  input  and/or  output  can  occur  are  treated  as  if 
they  are  files.   To  a  great  extent,  this  allows  the  user  of 
a  computer  with  a  UNIX  operating  system  to  direct  his 
attention  to  more  important  aspects  of  programming.   This 
concept  is  also  found  in  the  "c"  programming  language,  which 
is  essentially  the  language  of  UNIX,  and  which  is  the 
language  in  which  this  program  v»as  written.   In  "c", 
however,  a  distinction  is  made  between  the  standard  input 
and  output  (which  are  generally  the  keyboard  and  terminal 
screen),  a  data  file,  end  an  active  computer  program 
(process),  in  that  different  formats  must  be  used  to  receive 
input  from  or  direct  output  to  them.   In  most  programs  this 
would  not  be  a  major  concern,  but  this  program  by  design 
requires  the  use  cf  all  tnree  formats. 

As  described  earlier,  the  main  program  causes  a  second 
program  to  be  executed.   This  program  is  called  "readTN", 
and  buffers  the  output  from  telnet  (WES)  as  required.   The 
readTN  program  runs  as  a  background  process,  that  is,  it  is 
executed  by  UNIX  independently  of  the  main  program.   It 
receives  its  instructions  by  having  access  to  a  file  which 
contains  a  flag,  i.e.,  a  character  whose  value  determines 
whether  the  buffer  is  to  be  active  or  not.   The  main  ^rogrram 
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also  has  access  to  the  file  containing  the  flag,  and  by 
changing  the  character  in  the  file  causes  the  buffer  to  "be 
enabled  ("l")  cr  disabled  {"?"). 

The  main  program  also  requests  that  the  telnet  process 
be  initiated.   This  operation  is  handled  by  a  call  to  the 
UNIX  operating  system,  and  will  be  discussed  in  more  detail 
in  the  section  on  the  telnet  interface. 

C.   THE  WES  OUTPUT  BUE5ER  PROGRAM 

This  program,  "readTN",  is  essential  to  the  operation  c: 
the  filter  process.   Without  a  buffer,  the  output  from  WIS 
would  be  mixed  on  the  terminal  screen  with  the  output  from 
the  process  which  the  user  has  selected.   This  would  not 
have  any  effect  on  either  WES  or  the  user  program,  however, 
it  would  be  at  best  confusing  to  the  user.   An  additional, 
and  perhaps  more  sericus  problem  associated  with 
interleaving  the  two  outputs  is  that  the  user  would  be 
required  to  divide  his  attention  between  them.   Buffering 
the  WES  output  allows  him  to  concentrate  on  one  issue  at  a 
time,  and  to  be  quickly  brought  up  to  date  when  the  second 
process  is  completed. 

One  means  of  controlling  the  output  of  the  buffer  is  to 
use  the  X-ON/X-OFE  feature  which  is  a  part  of  UNIX.   In 
short,  if  the  terminal  page  length  ("pagelen")  is  not  zero, 
and  "flowcut"  is  enabled,  the  UNIX  operating  system  will 
send  the  output  from  WES  or  from  the  buffer  program  to  the 


terminal  screen  a  page  at  a  time.   To  continue  with  the  next 
page,  an  X-ON ,  which  is  currently  a  "ccntrol-Q",  is  typed 
in.   This  character  is  interpreted  by  UNIX,  but  is  not 
considered  to  be  a  valid  input  to  the  program.   Similarly,  a 
"control-S"  can  be  used  to  stop  the  output  before  the  end  of 
a  page  is  reached.   Rather  than  displaying  one  page  at  a 
time,  a  "control-P"  can  be  used  to  enter  the  "zoom  moae",  in 
which  the  output  dees  net  stop  at  the  end  cf  each  page.   The 
"control-F"  is  a  toggle,  that  is,  a  second  "ccntrol-P" 
causes  the  page  length  to  once  again  take  effect. 


D.   THI  TELNET  INTERFACE 

Although  not  obvious  in  the  source  cede,  significant 
problems  were  encountered  in  implementing  a  program  which 
provides  input  to  the  telnet  process.   The  author  of  telnet, 
Dan  Eranklin  of  Bolt,  Beranek,  and  Newman  (BBN),  stated  that 
he  did  not  anticipate  the  use  of  a  program  to  "feed  telnet" 
when  he  wrote  the  telnet  process.   He  agreed  that  the  input 
terminal  becomes  disabled  when  an  attempt  is  made  to  create 
a  connection  between  a  process  and  telnet.   This  terminal 
"lockup"  is  caused  by  the  telnet  program,  which  changes  the 
terminal  modes  in  such  a  manner  that  nc  input  can  be 
generated  from  the  keyboard.   This  only  occurs  when  a 
program  is  used  to  create  the  telnet  process.   With  this 
fact  in  mind,  the  program  was  written  to  reset  the  modes 
after  the  telnet  process  is  created,  so  that  the  keyboard 


will  be  reactivated.   This  is  accomplished  in  the  filter 
program  in  the  subroutine  " tnTops2£( ) "  . 

The  main  prcgram  creates  telnet  as  a  means  of  connecting 
the  computer  (a  PD?  11/70)  in  the  C2  Secure  Computer 
Laboratory  to  one  of  the  virtual  machines  at  the  Naval  Ocean 
Systems  Center  (NOSC)  in  San  Diego.   Aside  from  the  fact 
that  a  different  operating  system  is  being  used  after 
logging  in  to  the  system  at  NOSC,  telnet  itself  is 
transparent  to  the  user.   It  allows  prrgrams  and  processes 
to  be  run  frorr  the  terminal  as  if  a  physical  connection  to 
the  NOSC  computer  existed. 
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III.   A  USER'S  GUIDE 

The  purpose  of  this  section  is  to  provide  the  user  of 
the  filter  program  with  a  concise,  step-hy-step  set  of 
instructions  to  follow  in  becoming  familiar  with  the  filter 
program.   This  is  most  easily  accomplished  by  using  the 
training  mode,  since  the  output  of  the  program  which  would 
normally  be  sent  vie  telnet  to  WIS  can  be  displayed  on  an 
adjacent  terminal  for  easy  reference.   A  copy  of  a  training 
session  on  the  filter  program  is  found  in  Appendix  A. 

Three  steps  must  be  followed  in  order  to  begin  training 
on  the  filter  program.   First,  the  type  of  terminal  being 
used  must  be  specified.   This  choice  is  made  by  simply 
entering  the  number  from  the  menu  which  corresponds  to  the 
type  of  terminal  from  which  the  program  is  being  run. 
Second,  a  "c"   must  be  entered  to  use  the  program  in  the 
training  mode.   Finally,  the  letter  which  identifies  the 
terminal  to  which  the  "telnet"  output  is  to  be  sent  must  be 
entered.   Although  the  letters  whinh  correspond  to  the  Ann 
Arbor  terminals  are  shown  on  the  screen,  and  a  list  of  all 
possible  terminal  identifiers  is  shown,  this  may  not  be 
adequate  or  simple  enough  to  follow.   As  an  alternative, 
"login"  on  the  terminal  which  is  to  be  used  to  display  the 
output,  as  well  as  on  the  terminal  to  be  used  to  run  the 
filter  program.   On  the  keyboard  of  the  display  terminal, 


3c 


type  "dpy  yourname",  where  "yourname   is  the  narre  used  to 
login.   This  will  show  the  upper  or  lowercase  letter  which 
corresponds  tc  the  terminal,  cr  tty,  immediately  following 
the  user  name.   Enter  this  letter  when  asked  for  the  "tty 
you  want  to  link  to".   Note  that  unlike  many  programs,  the 
filter  program  reads  every  character  as  it  is  typed  in,  ana 
a  carriage  return  is  not  required  after  an  entry  is  made 
unless  it  is  specifically  askea  for,  or  after  "shelp", 
"Squit",  or  "smacro"  is  entered.   Messages  indicating  that 
the  link  is  being  established,  and  that  the  keyboard  can 
then  be  used  will  he  displayed  on  the  input  terminal. 

To  review  the  three  basic  types  of  entries  which  can  be 
made,  enter  "$  help",  followed  by  a  carriage  return.   It 
should  be  noted  that  this  and  any  other  entry  which  begins 
with  a  "$'  must  end  with  a  carriage  return  (CR),  or,  in  the 
case  of  macros,  alternatively  with  an  escape  character.   The 
three  entries,  "$  CR"  ,  "$  macro  CR",  and  "$  quit  CR"  cause 
the  menu,  a  macro  expansion,  and  termination  of  the  program 
to  occur  respectively. 

In  the  training  mode,  a  simulated  system  prompt  ("?")  is 
displayed  on  both  the  input  and  output  terminals,  since  it 
would  be  seen  if  telnet  was  being  used. 

After  reviewing  the  help  file,  input  "$  CR"  to  display 
the  menu  of  options.   Step  through  each  of  the  six  items  on 
the  menu,  returning  to  the  standard  WES  input  mode  by 
choosing  the  sixth  option.   At  this  time,  the  macro 
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expansion  capability  can  be  demonstrated .   If  a  copy  of  the 
file  "mac. text"  is  not  available,  return  to  the  menu,  edit 
the  macro  list  by  selecting  item  3,  and  write  down  one  or 
more  macros.   Enter  a  "$"  followed  by  the  macro  (with 
arguments,  if  any}  and  end  the  input  with  a  carriage  return. 
If  the  macro  has  been  entered  properly,  no  error  message 
will  be  displayed,  and  the  WES  command(s)  will  be  displayed. 
on  both  the  input  and  the  output  terminals.   Insure  that  the 
proper  number  of  arguments,  in  the  prcper  sequence,  are 
entered. 

For  easy  reference,  abbreviations  for  the  arguments  have 
been  included  in  each  macro  in  "mac. text".   For  example,  "s" 
must  be  replaced  by  a  ship  name,  "n"  by  a  flight  name,  and 
"#"  oy  the  quantity  of  items  (e.g.  F-14's)  which  are 
desired.   It  is  anticipated  that  a  paper  copy  of  the  macro 
file  will  be  helpful  and  should  be  available  if  a  relatively 
large  number  of  macros  are  being  used.   The  addition  of  the 
letters  to  represent  the  arguments  of  a  macro  should  also  be 
accomplished  vhen  a  new  macro  is  added  to  the  list,  to 
insure  that  it  is  properly  documented  for  future  use. 
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IV.   CONCLUSICNS  AND  RECOMMENDATIONS 

A.   CONCLUSIONS 

The  input  and  output  filter  program  has  been 
successfully  demonstrated  to  be  a  viable  concept  which 
interfaces  well  with  both  tbe  Warfare  Environment  Simulator 
(WES)  and  the  user.   At  the  present  time,  the  program  has 
been  tested  with  WES  being  run  using  several  different,  but 
predetermined  scenarios.   This  approach  has  been  sufficient 
to  detect  and  correct  deficiencies  in  the  prcgraas  which 
make  up  the  filter,  tut  a  recommendation  for  future  testing 
and  use  is  made  in  the  next  section. 


B.   RECOMMENDATIONS 

1 .   Future  Testing 

Although  the  program  was  tested  en  an  incremental 
basis  as  it  was  developed,  and  significant  changes  were  -nade 
to  insure  that  its  use  did  not  interfere  with  the  conduct  of 
a  WES  wargame  in  any  way,  mere  extensive  testing  should  be 
accomplished  as  follows.   The  program  should  be  used  during 
a  truly  interactive  wargame,  as  opposed  to  the  wargames 
which  have  recently  been  run  in  which  essentially  all  orders 
were  entered  from  a  prepared  script.   An  interactive  wargame 
v^ould  be  especially  useful  in  evaluating  the  actual  and 
potential  value  of  the  most  powerful  capability  which  the 


program  provides,  i.e.  macro  expansion.   An/  scenario  in 
which  the  player  is  forced  to  be  active  a  great  deal  of  the 
time  would  be  most  useful  in  accomplishing  this  evaluation. 
2.   Other  Applications 

A  general  observation  and  recommendation  for  further 
work  stems  from  the  fact  that  the  input/output  filter 
concept  has  an  unlimited  number  of  possible  applications. 
In  general,  interactive  computer  programs  such  as  WES  are 
readily  accessible,  but  not  flexible  or  easy  to  modify,  if 
they  can  be  changed  at  ail.   The  filter  concept,  on  the 
ether  hand,  provides  a  mechanism  for  achieving  a  wide  range 
of  flexibility  in  terms  of  aids  and  options  which  can  be 
provided  while  remaining  within  the  constraints  on  input 
imposed  by  an  otherwise  inflexible  process.   The  general 
structure  which  has  been  presented  here  should  serve  as  an 
adequate  baseline  from  which  to  develop  n-any  variations  of 
the  filter  program. 
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APPENDIX  A 
SAMPLE  OUTPUT  FROM  THE  FILTER  PROGRAM 

The  attached  text  is  a  copy  of  the  actual  output  of  the 
filter  program  when  used  in  the  training  rrode.   The  only 
significant  difference  between  the  output  shown  here  and  the 
output  when  the  prograrr  is  used  with  telnet  is  as  follows. 
In  telnet,  the  echo  is  provided  by  the  remote  host  (TOPS20), 
so  that  both  the  input  echo  and  the  output  from  WSS  appear 
in  capital  letters . 

The  copies  of  the  rrenu  of  options  which  occur  after  it 
is  displayed  the  first  time  have  been  removed  and  replaced 
with  "(MENU  HERE)"  . 
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